Clear Acceptance Criteria for
User Stories the BDD way🥒

The work of modern Agile teams involves the use of certain artifacts, among which are user requirements and acceptance criteria. The latter allows us to clearly formulate expectations from the final product and avoid misunderstandings between the customer and developers of this digital solution. Even though the importance of writing acceptance criteria is obvious, many teams either forget about it when creating a product backlog or do not determine acceptance criteria qualitatively.

When defining acceptance criteria, first of all, it should be mentioned that, together with the user story, they are the main ways of documenting the requirements for the developed product. The relationship between the user story and acceptance criteria is fundamental to Agile planning, ensuring that all team members understand what needs to be delivered.

In this article, we decided to figure out how to write good acceptance criteria for user stories. Let’s brief guide to acceptance criteria terminology (AC, using abbreviation to terminology)

What are the acceptance criteria in testing?

User story acceptance criteria are a list of conditions that an app must meet in order to fully fulfill the tasks assigned to it, highlighting the necessity of writing acceptance criteria that align with the end user’s needs. The software product must meet the target audience’s expectations and not contradict the main market application trends; in a word, it must be accepted by the general public and the direct customer.

It is worth noting that ACs are not repeated from one user story to another, and their task is to determine the options for feature usage by the end user.

AC are important for the development team to accurately understand the customer’s vision because each person may have a different perception of the same goal in software development (SDLC). And, accordingly, a different approach to its solution.

User story VS acceptance criteria

In contrast to the acceptance criterion, the user story describes a specific software function from the user’s point of view. The acceptance criteria’ purpose is to clearly articulate the task that the software product must perform in order to fulfil the client’s needs.

Here’s some background. In 2001, Ron Jeffries wrote about the Three C’s of the user story:

• Card – stories are traditionally written on notecards, and these cards can be annotated with extra details
• Conversation – details behind the story come out through conversations with the Product Owner
• Confirmation – acceptance tests confirm the story is finished and working as intended.

In a workflow based on the Agile methodology, user stories depict the project work yet to be performed by the team. Let’s look at the examples below 👀

Typically, user stories are written in the following format:

“As (the type of user) – I want (to do something) – so that I (can achieve a certain result, goal, or benefit).”

Although some teams in the same situation use abbreviated syntax, which speeds up the process of writing a user story.

In abbreviated format, the user story will look like this:

“User type – feature – result.” Logically, this result is our acceptance criteria ✅

All features that should be present in the program make up the product backlog. It is developed by the Project Manager(PM) or Product Owner(PO is the person who represents the customer for the thing you’re developing), taking into account the priority of implementing one or another functionality.

Acceptance criteria VS the definition of done

People are sometimes unsure of the difference between acceptance criteria and the definition of done. The key difference is that the definition of done applies to all your work, whereas acceptance criteria are specific to individual stories.

Example acceptance criteria

To illustrate the importance of well-written acceptance criteria, consider the next comparison of product filter categories on the e-shop site:

A client approached you to develop an e-commerce platform specializing in selling devices. They want users to be able to search for the products they want in certain categories (smartphones, tablets, laptops, etc.). The task can be understood ambiguously if you don’t write the acceptance criteria.

The first user story acceptance criteria example is to implement the search function in such a way that customers would have to specify the category of interest manually.

The second example is that the customer could imply selecting the desired product category from a ready-made catalog.

The result: due to the lack of clearly formulated AC, the ready-made software does not meet the client’s expectations.

Why do teams need clearly written acceptance criteria?

The fact that all team members need effective acceptance criteria is an undeniable fact, and we have already made sure of that. Let’s talk more about the benefits you can get from well-written acceptance criteria:

• Confirmation of user story completion. How does a developer know that a digital solution is working properly, that is, the user story is complete? Without clear criteria, it would be very difficult to do so.
• Reaching an understanding between a customer and a developer. Documented acceptance criteria will allow for meeting the expectations of both parties. The team of specialists working on the project clearly understands the client’s vision, and they, for their part, know in advance what they will get from the software solution.
• Optimal workflow planning. Given the fact that each user story is an unfinished task facing the team of developers, its exact description by creating acceptance criteria allows you to understand how important each such task is and to properly prioritize the work.
• Reliable basis for the acceptance tests. Clearly written acceptance criteria can be used as the basis for subsequent product testing. For this purpose, the result of checking AC and compliance of a particular function with it is used. There can be two options for this result: Pass or Fail.

Properly written user stories and acceptance criteria greatly simplify the testing and development process, so do not disregard this format for documenting the requirements for a future app.

Who is responsible for acceptance criteria?

It is a mistake to think that only business analysts can create acceptance criteria. The necessary knowledge and skills should guide all Agile team members and even the customer in this matter. Let’s look at a few options for who writes acceptance criteria:

Client-side presents competent personnel in the writing project documentation

This is a great way to build close cooperation between the client and the technical team. However, you should consider that even if the client has some experience in development and testing, it is still better to check the AC written by them before starting to work on the project. They should be clearly formulated and strictly correspond to the development process.

The responsibility for writing the AC is on the development team

If the customer decided to entrust the creation of the criteria to specialists, this task can be undertaken by any team member who knows the intricacies of implementing the app functionality and is aware of the technology stack used:

• QA Analyst
• Project Manager (PM)
• Tester (QA engineer or QA cordinstor)
• Business Analyst (BA).

Whoever is writing the acceptance criteria should do it in time, not before the start of development. This will help you better understand what you should work on first and what tools to choose to implement the necessary functions. Additionally, these criteria should be aligned with the relevant user stories to ensure that they meet the end-users’ expectations and requirements effectively.

BDD way: Agile acceptance criteria Given/When/Then

Based on the tasks set before the developers and the existing goals of the project, you can choose one of three varieties of AC:

• scenario-oriented acceptance criteria
• rule-oriented criteria
• custom acceptance criteria formats

The first two formats are the most common, so let’s talk about them in more detail. The scenario-oriented format aligns closely with user stories, helping to ensure that development matches end-user needs. The rule-oriented acceptance criteria format focuses more on technical specifications and rules. Both methods aid in creating clear, testable acceptance criteria to guide the development process.

Scenario-oriented approach

This approach is popular because it can significantly reduce the time required to create test cases. After all, the app’s behavior will be described in advance. It is based on the principles of Behavior Driven Development, and the main distinguishing features are a clear structure and consistency.

Scenario-oriented AC involves writing using the Given/When/Then sequence, and it looks like this:

User Story:

As a user, I want to be able to log in through my Google account to get quick access to my account in the app

Scenario: Quick access to the system. 
Given: a user enters the login page. 
When: a user presses the Google button. 
Then: a system offers to select the needed account. 
And: a user enters their account information.

Rule-oriented AC

If you describe functions in your user stories that are difficult to fit into the GWT framework, or the end user doesn’t need such detailed test cases, you can choose another approach to writing acceptance criteria, which is called Rule-oriented. As the name implies, this acceptance criteria format is a list of rules arranged as a bulleted list. In practice, it looks like this:

User Story:

As a user, I want to be able to enter the name of the city and the area in the search field so that I can find a suitable rented apartment.

Acceptance criteria of search interface:

How to write acceptance criteria?

Some recommendations from the professionals. Regardless of what agile development methodology you practice and what project management system you work with, there are general guidelines for writing AC that will help optimize the development process.

• Be sure to add acceptance criteria for all user stories. Remember that each user story is an unfulfilled task of the Agile team. And acceptance criteria clarify exactly how this task should be implemented. So you need to write at least one criterion.
• Create AC before you start software development. We want to draw your attention once again: writing AC after the start of the project will not allow you to understand customer expectations at the very beginning of cooperation. It can lead to problems in the implementation of the customer’s vision. Therefore, define acceptance criteria first and start development based on them.
• Avoid overly specific criteria. If you imply a specific solution for each AC, this leaves no room for developers to maneuver. In addition, other user behavior options may be missed in the testing process, greatly increasing the likelihood of failure.
• Too broad acceptance criteria are also bad. Effective acceptance criteria define for developers how much code to write and when it’s time to stop. If you make them too extensive, the user story will become incomprehensible and will be of no value to the team.
• Write independently testable AC. When writing the criteria, leave the option to test each of them independently from the others. Once you get a result (Pass or Fail), you can use them as the basis for acceptance testing.
• Avoid technical details. One of the benefits of the BDD methodology is the ability for non-technical experts to participate in the process of creating and testing software. This is achieved because all project documentation is written in an understandable language that is available to business analysts, product owners, and even customers. Adhere to this principle, including when writing AC.
• Consult with the client. Take into account that the options for using a particular feature may be formulated differently by the customer and developers. Therefore, when compiling the acceptance criteria, be sure to clarify the opinion of all other stakeholders and reach consensus on the vision of the implementation of the software functionality.
• Don’t write too much AC for one user story. The optimal number of criteria for one uncompleted task is no more than three. If there are significantly more (from six), it makes sense to divide the user story into several. This practice allows for faster delivery, and faster feedback and minimizes the risk of failure.

Despite the fact that when writing test cases in BDD format, you use clear, human-readable language, creating AC can be difficult. The above recommendations will help you avoid documentation errors and simplify the development process.

As you noticed, we a little bit expanded the well-known INVEST model criteria of Agile user stories:

• Independent
• Negotiable
• Valuable
• Estimable
• Small
• Testable

What should be in acceptance criteria, and what’s best to avoid?

In addition to the above recommendations, there are rules for formulating good acceptance criteria that will help make them clear and thus improve cooperation both within the Agile team and between developers and customers.

#1: Avoid negative sentences

Conditions that contain the particle “not” imply that the action must not happen under any circumstances. It takes too much time to check this condition, which makes it almost impossible. The best way out is to rewrite the user story or AC without the negation.

For example, acceptance criteria:

❌ “The system must not fail”

✅ Is better rewritten as: “The system must be available 85% of the time.”

#2: Refuse to use the passive voice

If the condition is written in the passive voice, it may not be clear who should perform a particular action. This will lead to AC ambiguity. Therefore, it is better to use the active voice when the subject performs an action (the predicate).

For example, acceptance criteria:

❌ “A link to the entered email address must be sent” does not have the clarity you want.

✅ It would be better changed to “The system sends a link to the entered email address.”

#3: Use nouns instead of pronouns

The use of pronouns is another reason why the acceptance criteria can become ambiguous. This is especially true when pronouns replace elements that appear in other requirements.

For example:

Scenario: User forgot password.

Given: The user goes to the login page.
When: The user clicks the Forgot Password button.
And: The user enters an email address to get a link to recover it.

In this example it is better to write the last sentence without using a pronoun:

And: enters an email address to get a link to recover the password.

#3: Try to use fewer conjunctions

If you use in acceptance criterion “and,” “or,” “as well as” “but” in most cases, it means that such AC can be divided into several. That is, to make it clearer.

For example:

Given: I am a user who has logged out, and I am on the login page

In this AC, the use of the conjunction “and” is inappropriate. It is more appropriate to split it into two criteria:

Given: I am a user who is logged out
And: I am on the login page

#4: Set achievable requirements

Using the words “always”, “never”, “all”, “100%” when formulating the criteria will not allow you to check such a condition, because it is almost impossible to achieve absolute values.

Let’s return to the example of a system that must not fail.

❌ The requirement “The system must always be available” is unattainable.

✅ It is better to formulate this condition more objectively: “The system must be 90% available.”

Wrap-up: Make acceptance criteria part of your user stories

We hope that the acceptance criteria examples and recommendations in this material will help you in writing good acceptance criteria and conducting effective acceptance tests.

Also, allow development teams to reach consensus with customers and develop software that fully meets the needs of end users.

Frequently asked questions